```markdown
# 📋 Инструкция пользователя: Генератор технологических карт санитарной обработки

**Версия 4.1.0 | Chemitech**

---

## Содержание

1. [О продукте](#1-о-продукте)
2. [Первоначальная настройка](#2-первоначальная-настройка)
3. [Подготовка чек-листа](#3-подготовка-чек-листа)
4. [Наполнение базы данных](#4-наполнение-базы-данных)
5. [Генерация техкарты](#5-генерация-техкарты)
6. [Работа с историей](#6-работа-с-историей)
7. [Администрирование базы данных](#7-администрирование-базы-данных)
8. [Импорт и экспорт данных](#8-импорт-и-экспорт-данных)
9. [Настройка категорий помещений](#9-настройка-категорий-помещений)
10. [Часто задаваемые вопросы](#10-часто-задаваемые-вопросы)

---

## 1. О продукте

**Генератор технологических карт** — это веб-приложение для автоматического создания технологических карт санитарной обработки помещений на основе чек-листов формата `.docx`.

### Что делает сервис

- Читает чек-листы осмотра помещений (Word)
- Подбирает инструкции по обработке из базы данных
- Группирует объекты с одинаковыми режимами обработки
- Формирует готовую технологическую карту в формате Word
- Раскрашивает названия моющих средств в соответствии с брендом Chemitech
- Учитывает категорию помещения для выбора правильных инструкций

### Где работает

- На сервере организации (через Docker)
- На локальном компьютере
- Доступ через браузер с ПК, планшета или телефона

---

## 2. Первоначальная настройка

### Шаг 1. Запуск приложения

**Способ А — через Docker (рекомендуется для сервера)**

```bash
docker build -t tech-cards .
docker run -d --name tech-cards -p 5000:5000 -v tech-cards-data:/app/data tech-cards
```

**Способ Б — локальный запуск**

```bash
# Установка
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# или .venv\Scripts\activate  # Windows
pip install -r requirements.txt

# Инициализация базы данных (только первый раз)
python -m db.init_db

# Запуск
python app.py
```

### Шаг 2. Открытие в браузере

| Страница | Адрес | Назначение |
|----------|-------|------------|
| Главная | `http://localhost:5000` | Загрузка чек-листов и генерация |
| База данных | `http://localhost:5000/admin` | Управление объектами и инструкциями |
| История | `http://localhost:5000/history` | Просмотр и скачивание готовых карт |

### Шаг 3. Импорт начальных данных (опционально)

Если у вас есть готовый CSV-файл с инструкциями:

```bash
python import_csv_to_db.py db_export_all1111.csv --mode 1
```

Или через веб: **База данных → Импорт CSV**.

---

## 3. Подготовка чек-листа

Чек-лист — это документ Word (`.docx`), который заполняется при осмотре помещения.

### Структура чек-листа

Чек-лист должен содержать:

1. **Заголовок** — предприятие и название участка
2. **Выпадающий список** — категория помещения (производственное, складское, инженерное, вспомогательное)
3. **Таблицу с объектами** — чек-боксы и названия поверхностей/оборудования

### Как создать выпадающий список

В Microsoft Word:

1. Вкладка **Разработчик** → **Элемент управления содержимым «Раскрывающийся список»**
2. Нажать **Свойства**
3. Добавить значения: `Производственное`, `Складское`, `Инженерное`, `Вспомогательное`
4. Нажать **ОК**

### Как отметить объекты

Используйте чек-боксы:

| Символ | Значение |
|--------|----------|
| ☒ | Объект **присутствует** — будет добавлен в техкарту |
| ☐ | Объект **отсутствует** — не добавляется |

### Пример заполнения

```
☒ потолок (высота 3м) ☒ П ☒ ОК
```

Где:
- `потолок` — базовый объект
- `П` — модификатор «подвесной»
- `ОК` — модификатор «окрашенный»

Результат в техкарте: **потолок подвесной окрашенный**.

### Важные правила

- Один чек-бокс в ячейке → одиночный объект
- Два и более → объект с модификаторами
- Базовый объект отмечен + модификаторы отмечены → каждый в свою категорию
- Базовый отмечен + модификаторы не отмечены → объект в «Прочее»
- Базовый не отмечен → объект не добавляется

---

## 4. Наполнение базы данных

База данных содержит три типа записей:

| Тип | Описание | Пример |
|-----|----------|--------|
| **Объект** | Что обрабатываем | потолок окрашенный, пол, раковина |
| **Инструкция** | Как обрабатываем | мойка средством X, концентрация Y |
| **Категория помещения** | Для какого типа помещения | Производственное, Складское |

### Добавление объекта вручную

1. Откройте **База данных** (`/admin`)
2. Нажмите **Добавить**
3. Заполните поля:
   - **Название** — как будет отображаться в техкарте (например, «потолок окрашенный»)
   - **Normalized name** — для поиска (например, «потолок окрашенный»)
   - **Приоритет** — число от 10 до 200 (определяет порядок в техкарте, см. таблицу ниже)
   - **Категория** — выберите из списка
4. Нажмите **Создать**

### Приоритеты объектов

| Приоритет | Что размещается |
|-----------|----------------|
| 10-50 | Потолок, светильники, вентиляция, вытяжные зонты |
| 55-90 | Стены, окна, двери, выключатели, завесы |
| 100-130 | Сантехника, санитарный пост, дозаторы |
| 130-150 | Мебель (столы, стулья, шкафы, полки) |
| 150-170 | Оборудование (тепловое, холодильное, технологическое) |
| 170 | Моечный инвентарь (мопы, ветошь, щётки, вёдра) |
| 175-200 | Пол, трапы, стоки, коврики, паллеты |

### Добавление инструкции к объекту

1. Найдите объект в таблице
2. Нажмите кнопку 📋 (Инструкции)
3. Нажмите **Добавить**
4. Заполните поля:

| Поле | Что указать | Пример |
|------|------------|--------|
| **Категория помещения** | Для какого типа помещения | Производственное (или «Общая») |
| **Способ обработки** | мойка / дезинфекция / обеспыливание / очистка / ополаскивание | мойка |
| **Средство** | Название препарата | ХИМИТЕК УНИВЕРСАЛ-ПД-Н |
| **Метод уборки** | Как наносится | ручной (протирание, обработка щёткой) |
| **Концентрация** | % и способ разведения | 3,0-4,0%, дозирующая система ProMax |
| **Температура** | Температура раствора | не ниже 40°C |
| **Время выдержки** | Сколько действует | 20 мин |
| **Инвентарь** | Чем обрабатывают | промаркированный |
| **Периодичность** | Как часто | 1 раз в месяц |
| **Исполнитель** | Кто выполняет | сотрудник внутреннего клининга |
| **Метод контроля** | Кто проверяет | визуальный контроль/сотрудник отдела качества |

5. Нажмите **Сохранить**

### Особенности инструкций

- У одного объекта может быть несколько инструкций (мойка + дезинфекция)
- Инструкции с одинаковым способом обработки и разной категорией помещения считаются **разными**
- Если инструкция для конкретной категории помещения не найдена — используется **общая** (без категории)

---

## 5. Генерация техкарты

### Пошаговая инструкция

1. Откройте **Главную страницу** (`/`)
2. Перетащите чек-лист в зону загрузки или нажмите для выбора файла
3. Выберите режим генерации:
   - **По категориям** — с заголовками категорий, объекты по алфавиту
   - **По приоритету** — единый список, сверху вниз (от потолка к полу)
4. Нажмите **Сгенерировать техкарты**
5. Дождитесь завершения (прогресс-бар покажет этапы)
6. Скачайте готовый файл или ZIP-архив

### Что происходит при генерации

1. **Парсинг** — чек-лист читается, извлекаются отмеченные объекты
2. **Поиск в БД** — для каждого объекта находятся инструкции
3. **Фильтрация по категории помещения** — выбираются инструкции для конкретного типа помещения
4. **Группировка** — объекты с одинаковым набором инструкций объединяются
5. **Сортировка** — инструкции выстраиваются в порядке: обеспыливание → очистка → мойка → ополаскивание → дезинфекция
6. **Заполнение шаблона** — строки таблицы заполняются данными
7. **Объединение ячеек** — ячейки с одинаковыми значениями объединяются
8. **Цветовое кодирование** — ячейки со средствами окрашиваются
9. **Сохранение** — файл сохраняется в формате `.docx`

### Режимы генерации

| Режим | Описание | Когда использовать |
|-------|----------|-------------------|
| **1 — По категориям** | Группировка по 15 категориям с заголовками | Для детального просмотра по типам объектов |
| **2 — По приоритету** | Единый список, сверху вниз (потолок→пол) | Для компактной карты, удобной в работе |

---

## 6. Работа с историей

Страница **История** (`/history`) хранит все сгенерированные техкарты.

### Возможности

| Действие | Как сделать |
|----------|------------|
| **Скачать** | Нажать кнопку 📥 в строке файла |
| **Удалить выбранные** | Отметить чек-боксы → нажать «Удалить» |
| **Удалить все старше даты** | Выбрать дату → нажать «Удалить» |
| **Навигация** | Использовать пагинацию внизу страницы |

### Особенности

- Хранится до 1000 записей
- При превышении лимита старые записи автоматически удаляются
- Файлы техкарт старше определённой даты можно удалить массово

---

## 7. Администрирование базы данных

### Поиск объектов

1. Откройте **База данных** (`/admin`)
2. Введите название в поле поиска
3. Результаты фильтруются по:
   - Названию объекта
   - Категории
   - Normalized name

### Сортировка

Нажмите на заголовок любой колонки для сортировки. Повторное нажатие меняет направление (возрастание/убывание).

### Редактирование объекта

1. Найдите объект
2. Нажмите ✏️ (карандаш)
3. Измените поля
4. Нажмите **Сохранить**

### Удаление объекта

1. Найдите объект
2. Нажмите 🗑️ (корзина)
3. Подтвердите удаление

**⚠️ Внимание:** При удалении объекта удаляются все его инструкции.

### Редактирование инструкций

1. Найдите объект
2. Нажмите 📋 (список)
3. В открывшемся окне:
   - Чтобы **добавить** — кнопка «Добавить»
   - Чтобы **изменить** — отредактируйте поля и нажмите «Обновить»
   - Чтобы **удалить** — нажмите 🗑️ в строке инструкции

---

## 8. Импорт и экспорт данных

### Экспорт CSV

Используется для резервного копирования или переноса данных.

1. Откройте **База данных** (`/admin`)
2. Нажмите **Экспорт CSV**
3. Файл `db_export.csv` будет скачан

Формат файла:
```
object_id;category_name;normalized_name;display_name;...;room_category_name;cleaning_method;...
```

### Импорт CSV

Используется для загрузки данных из внешнего источника.

1. Откройте **База данных** (`/admin`)
2. Нажмите **Импорт CSV**
3. Выберите файл `.csv`
4. Выберите режим:

| Режим | Описание | Когда использовать |
|-------|----------|-------------------|
| **1** | Добавление новых (пропуск дубликатов) | Обычное пополнение БД |
| **2** | Очистка данных + добавление | Полная замена данных |
| **3** | Пересоздание БД | Сброс и восстановление из CSV |

5. Нажмите **Загрузить**

### Структура CSV для импорта

Обязательные колонки:
- `category_name` — категория объекта
- `normalized_name` — нормализованное имя
- `display_name` — отображаемое имя
- `cleaning_method` — способ обработки
- `product_name` — название средства

Опциональные колонки:
- `room_category_name` — категория помещения (пустая = общая инструкция)
- `sort_priority` — приоритет объекта
- `frequency`, `executor`, `control_method` и др.

---

## 9. Настройка категорий помещений

Категории помещений позволяют задавать разные инструкции для одного объекта в разных типах помещений.

### Стандартные категории

| Категория | Примеры помещений |
|-----------|------------------|
| **Производственное** | Цеха, производственные участки |
| **Складское** | Склады сырья, готовой продукции |
| **Инженерное** | Серверные, щитовые, венткамеры |
| **Вспомогательное** | Коридоры, бытовки, санузлы |

### Как это работает

**Пример:** Для объекта «пол» могут быть разные инструкции:

| Категория | Периодичность | Исполнитель |
|-----------|--------------|-------------|
| Производственное | 2 раза в смену | Сотрудник внутреннего клининга |
| Складское | 1 раз в смену | Сотрудник склада |
| Инженерное | 1 раз в неделю | Сотрудник инженерной службы |

При генерации:
1. Парсер читает категорию помещения из выпадающего списка в чек-листе
2. Для каждого объекта ищется инструкция с соответствующей категорией
3. Если специфичная инструкция не найдена — используется **общая** (без категории)

### Создание новой категории

Через API:
```bash
curl -X POST http://localhost:5000/api/room-categories \
  -H "Content-Type: application/json" \
  -d '{"name": "Новая категория"}'
```

### Редактирование категории

Через API:
```bash
curl -X PUT http://localhost:5000/api/room-categories/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Изменённое название"}'
```

---

## 10. Часто задаваемые вопросы

### ❓ Объект попадает в «Прочее», хотя должен быть в другой категории

**Причина:** Normalized name в БД не совпадает с тем, что приходит из парсера.

**Решение:**
1. Откройте **База данных** → найдите объект
2. Нажмите ✏️ → проверьте поле **Normalized name**
3. Оно должно точно совпадать с тем, что парсер извлекает из чек-листа

### ❓ Инструкции исчезают после перезапуска

**Причина:** База данных не сохранена в persistent volume (Docker) или лежит в папке, которая очищается.

**Решение:**
- **Docker:** Убедитесь, что папка `/app/data` смонтирована как volume
- **Локально:** Не удаляйте файл `tech_cards.db`

### ❓ Неправильный порядок способов обработки в техкарте

**Причина:** Устаревшая версия генератора.

**Решение:** Обновите `generator/docx_generator.py` до версии 4.1.0. Порядок фиксирован: обеспыливание → очистка → мойка → ополаскивание → дезинфекция.

### ❓ Ячейки в колонках «Периодичность» / «Исполнитель» не объединяются

**Причина:** Значения в соседних строках различаются.

**Решение:** Проверьте инструкции объекта. Объединение происходит только для последовательных строк с **одинаковыми** значениями.

### ❓ Файл не открывается в Word

**Причина:** Повреждённая структура XML при генерации.

**Решение:**
1. Проверьте логи в консоли
2. Перезапустите генерацию
3. Убедитесь, что шаблон `tech_card_templates/шаблон.docx` не повреждён

### ❓ Шрифт в техкарте не Arial

**Причина:** Шаблон не настроен.

**Решение:**
1. Откройте `tech_card_templates/шаблон.docx` в Word
2. Выделите всё (`Ctrl+A`)
3. Установите шрифт **Arial**, размер **9**
4. Обновите стиль «Основной текст»
5. Сохраните

### ❓ Медленная генерация (больше 10 секунд)

**Причина:** Много объектов или сложная структура чек-листа.

**Решение:**
- Убедитесь, что используется последняя версия генератора (3 запроса на техкарту)
- Проверьте, что в чек-листе нет лишних объектов
- Для массовой генерации используйте CLI: `python test_generator.py --input "checklists" --output "tech_cards" --mode 2`

---

## Горячие клавиши и быстрые действия

| Действие | Как выполнить |
|----------|--------------|
| Загрузить чек-лист | Перетащить файл в зону Drag & Drop |
| Сгенерировать | Кнопка «Сгенерировать техкарты» |
| Скачать ZIP | Кнопка «Скачать все одним архивом» |
| Начать заново | Кнопка «Новая генерация» |
| Найти объект | Поле поиска в админ-панели |
| Отсортировать таблицу | Клик по заголовку колонки |

---

## Контакты и поддержка

По вопросам использования и доработки обращаться к разработчику.

---

**Версия инструкции:** 1.0  
**Актуально для версии продукта:** 4.1.0  
**Дата:** 27 апреля 2026 г.
```